<HTML>
<h1 align="center">Cheat Sheet enhancements for Eclipse 3.2 proposal</h1>
<p>Draft: 0.5</p>
<p>By Chris Goldthorpe and Dejan Glozic, IBM</p>
<h2>Background</h2>
<p>This document describes in more detail the features described in the&nbsp;
<a href="http://www.eclipse.org/eclipse/development/eclipse_project_plan_3_2.html">
Eclipse Platform Project 3.2 Plan</a>&nbsp; paragraph titled &quot;Improve cheat 
sheet support&quot;.&nbsp;&nbsp; There are several motivations for enhancing 
cheat sheet&nbsp;support in Eclipse 3.2. Users need to be able to create and 
test cheat sheets quickly. Cheat sheets currently work best when the number of 
steps is small (less than 10) and the steps are always performed in the same 
order. There is a need to improve scalability and be able to handle much larger numbers of steps. Cheat sheets in Eclipse 3.1 can initiate 
actions but not commands which are 
replacing most uses of actions. Cheat sheets need to have a better way to 
recognize successful completion.</p>
<h2>Overview</h2>
<p>There are five areas in which cheat sheets will be enhanced:</p>
<ol>
	<li>Support for commands and linkability</li>
	<li>Launching from a file</li>
	<li>Scalability</li>
	<li>Saving current state in a file </li>
	<li>Better recognition of success</li>
</ol>
<p>Command and Linkability support will give cheat sheets the ability to initiate 
commands or follow links which will make it possible to author cheat sheets which 
initiate predefined commands without the need to write Java code.</p>
<p>Launching from a file or URL will be valuable for authors as well as regular 
users of cheat sheets. Authors will be able to develop cheat sheets without having 
to launch a runtime workbench to test that the xml is formed correctly. 
Cheat sheets which do not contain user-defined actions can now be opened directly 
from the file system or even from a Web server. </p>
<p>Cheat sheets do not scale well beyond about 10 steps. Instead of modifying 
cheat sheet themselves to handle more steps in a scalable manner, we will 
introduce a notion of tasks that can be completed independently.</p>
<p>Saving state in a file allows the state of cheat sheets to 
be shared between different members of a team.</p>
<p>Better recognition of success will be accomplished by extending the schema 
for cheat sheets to allow the author to define text which will be displayed after 
a step has been completed.</p>
<h3>Command and Linkability Support </h3>
<p> Eclipse is moving towards the use of Commands and Handlers rather than 
Actions. Cheat sheets in Eclipse 3.1 can initiate actions which are defined in 
the xml file for the cheat sheet using an action element as in the example below:</p>
<blockquote>
	<pre>&lt;item title=&quot;Open the Java Perspective&quot;&gt;
  <b>&lt;</b>action pluginId=&quot;org.eclipse.ui.cheatsheets<b>&quot;
          </b>class=&quot;org.eclipse.ui.internal.<span style="color: highlighttext; background: highlight">cheatsheets</span>.actions.OpenPerspective&quot;<b>
&nbsp;         </b>param1=&quot;org.eclipse.jdt.ui.JavaPerspective&quot;/&gt;<b>
&lt;</b>/item<b>&gt;</b></pre>
</blockquote>

<p>In Eclipse 3.2 a new element <code>command</code> will be added to the schema for cheat sheets 
which can be a child of <code>item</code>,&nbsp; <code>subitem</code> or <code>perform-when</code>.&nbsp; 
This will allow the cheat sheet to call a command and pass in parameters. An 
<code>item</code>, <code>subitem</code> or <code>perform-when</code> may not have both a command and an action 
associated with it. The example below shows an item which contains a command 
with a parameter. </p>
<blockquote>
	<pre>&lt;item title=&quot;Open the Package Explorer&quot;&gt;
  <b> &lt;</b>command id=&quot;org.eclipse.ui.views.showView<b>&quot;
            </b>param1=&quot;org.eclipse.jdt.ui.PackageExplorer&quot;/&gt;<b>
&lt;</b>/item<b>&gt;</b></pre>
</blockquote>
<p>Linkable references will also be introduced in Eclipse 3.2 and a <code>linkable</code> 
element will be added to the schema for cheat sheets. A linkable reference 
provides another alternative to commands and actions and a <code>linkable</code> can appear 
in any of the same places that an &lt;action&gt; or command could occur. Linkables 
do not have parameters. Here is an example of a linkable:</p>
<blockquote>
	<pre>&lt;item title=&quot;Open the Package Explorer&quot;&gt;
  <b> &lt;</b>linkable url=&quot;url_of_a_linkable_object<b>&quot; </b>/&gt;<b>
&lt;</b>/item<b>&gt;</b></pre>
</blockquote>
<p><font color="#000080"><span style="font-weight: 400; font-style: italic">
Note: support for linkability is currently being integrated into the overall 
command framework. The linkable URL will essentially be another way of executing 
a command. For example, executing a command 'com.example.xyz.foo' with a 
parameter 'p1' and value 'v1' can be done in two ways:</span></font></p>
<blockquote>
	<pre><i><font color="#000080">&lt;command id=&quot;com.example.xyz.foo&quot; param1=&quot;v1&quot;/&gt;</font></i></pre>
	<pre><i><font color="#000080">or</font></i></pre>
	<pre><i><font color="#000080">&lt;linkable url=&quot;command:com.example.xyz.foo?p1=v1&quot;/&gt;</font></i></pre>
</blockquote>
<h3>Launch a Cheat sheet from a File or URL </h3>
<p> Cheat sheets can be contributed using an extension point. In Eclipse 3.2&nbsp; 
an additional method for launching cheat sheets will be introduced which allows 
the data for a cheat sheet to be read from a file or URL. This will make cheat sheet authoring 
easier as a new workbench does not need to be started to test a 
cheat sheet. It will also make it possible to launch a cheat sheet hosted on the 
file system or the internet. The cheat sheet selection dialog which is displayed 
when the user selects Help / Cheat sheets will be modified to add the option to 
launch a cheat sheet by reading the xml file from either a file in the workbench or from a URL.</p>
<p> Class<code> OpenCheatSheetAction</code> will be modified that it can allows 
launching cheat sheets from a file. This is not an API change - the constructor <br>
<code>public OpenCheatSheetAction(String id, String name, URL url)</code>&nbsp; already 
exists but does not accept <code>file: </code>urls (see Bugzilla defect 88481).</p>
<h3>Improving scalability</h3>
<p>Cheat sheets in Eclipse 3.1 are well suited to performing a sequence of 3-10 
steps where the steps are always performed in the same order. As more steps are 
added it becomes harder to write a useful cheat sheet. Consideration was given to 
nesting cheat sheets or allowing items to contain other items but this would 
result in the text getting indented further to the right and would not give the 
ability to perform steps in different orders. Instead the proposal is to allow 
cheat sheets to be aggregated into a set of tasks. The platform will support informational tasks and cheat sheet 
tasks, while extensibility will allow for additional kinds of tasks to be 
contributed.</p>
<p><i><font color="#000080">Note: the term 'task set' is used in this section to 
provide for describing the proposed new technology for improving cheat sheet 
scalability. It may not survive this proposal and a better term may be chosen. 
We welcome feedback on naming the collection of interdependent tasks by Eclipse 
Milestone 5 (mid February).</font></i></p>
<p>Cheat sheets with <b>task sets</b> will open in the cheat sheet view with a &quot;task navigator&quot; being displayed 
above a task detail section. The task navigator is by default a tree, 
while extensibility will permit different representations for the navigator. The task detail will display UI applicable to the 
selected 
task. For a&nbsp;cheat sheet task the cheat sheet would be displayed. If the 
view is wider than it is tall the sections are stacked horizontally instead of 
vertically. The screenshot below shows an example of a cheat sheet with a task 
set:</p>
<p align="center"><a href="SolutionGuideView.PNG">
<img border="0" src="OpenGuide.PNG" width="286" height="416"></a></p>
<p>A task set is defined in the cheat sheet XML file and consists of&nbsp; a set of tasks. 
Each task has a title and all tasks except informational tasks will have a task 
kind and parameters. A task may&nbsp; have 
an id and may also contain dependencies on previous tasks. The meaning of the parameters depends on the kind of the task, for a cheat sheet the&nbsp;id of the cheat sheet 
is a required parameter.&nbsp;&nbsp; Tasks may also contain <code>intro</code> 
elements which contain the text to be displayed before the task has been started 
and <code>onCompletion</code> elements which contain the text to be displayed 
once the task is completed. Both the <code>intro</code> and <code>onCompletion</code> elements may contain 
form text markup, in this example the tags &lt;b&gt; and &lt;/b&gt;, which are escaped in 
the xml to &amp;lt;b&amp;gt; and &amp;lt;/b&amp;gt; are used to make text bold.</p>
<p>Here is the xml file for the task set displayed above:</p>
<blockquote>
	<pre>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;taskSet title=&quot;Building and Publishing Plugins&quot;&gt;
  &lt;task title= &quot;Introduction to the PDE&quot;&gt;
    &lt;intro&gt; This solution guide contains cheatsheets which can guide you through the &amp;lt;b&amp;gt;PDE&amp;lt;/b&amp;gt;, 
            from creating a simple project to deploying a feature 
    &lt;/intro&gt;
    &lt;task kind=&quot;cheatsheet&quot; title= &quot;Create a java project&quot; id = &quot;createJavaProject&quot;&gt;
      &lt;param name=&quot;id&quot; value = &quot;org.eclipse.jdt.helloworld&quot;/&gt;
      &lt;intro&gt;This task guide walks through the process of creating a simple hello world application. 
              The guide can launch wizards to create a new project and a new class. 
      &lt;/intro&gt;
      &lt;onCompletion&gt;Congratulations you have succeeded in creating a hello world application&lt;/onCompletion&gt;
    &lt;/task&gt;
    &lt;task kind=&quot;cheatsheet&quot; title= &quot;Deploy a java project&quot;&gt;
      &lt;intro&gt;
        In this task the hello world project created in a previous task will be deployed. 
        This task guide shows show to create &amp;lt;b&amp;gt;features&amp;lt;/b&amp;gt; and &amp;lt;b&amp;gt;update sites&amp;lt;/b&amp;gt;
      &lt;/intro&gt;
      &lt;dependsOn task = &quot;createJavaProject&quot; /&gt;
      &lt;param name = &quot;id&quot; value = &quot;org.eclipse.pde.updates&quot; /&gt;
    &lt;/task&gt;

    &lt;task title= &quot;Next Steps&quot;&gt;
      &lt;intro&gt;
        Once you have learned how to create and deploy a java project you may want to learn 
        about SWT and Rich Clients. 
      &lt;/intro&gt;

      &lt;task kind=&quot;cheatsheet&quot; title= &quot;Create an SWT application&quot;&gt;
        &lt;param name = &quot;id&quot; value = &quot;org.eclipse.jdt.helloworld.swt&quot; /&gt;
        &lt;intro&gt;
           Eclipse plugins which contribute to the user interface use The Standard Widget Toolkit (SWT). 
           This task guide can be used to learn more about SWT. 
        &lt;/intro&gt;

      &lt;/task&gt;
      &lt;task kind=&quot;cheatsheet&quot; title= &quot;Create a Rich Client application&quot;&gt; 
        &lt;param name = &quot;id&quot; value =&quot;org.eclipse.pde.rcpapp&quot; /&gt;
        &lt;  intro&gt;
          The minimal set of plug-ins needed to build a rich client application is 
          collectively known as the Rich Client Platform. This task guide walks through the steps 
          to create a rich client application.
        &lt;/intro&gt;
     &lt;/task&gt;
  &lt;/task&gt;
  &lt;/task&gt;
&lt;/taskSet&gt;</pre>
</blockquote>
<p><br>
In this task set &quot;Deploy a Java Project&quot; depends on &quot;Create a Java 
Project&quot; and cannot be performed until &quot;Create a Java Project&quot; has been 
completed.&nbsp; If the prerequisites for a task have not been completed then 
that task cannot be started.</p>
<p>When the user selects a task from the task navigator that task will be opened 
in the lower pane. When a task&nbsp; is first selected&nbsp; just the 
introduction is displayed with a button to start of the task. Once the 
cheat sheet is started the other steps would show up as in the screenshot above. 
When the last step is completed a completion message will appear in the task 
detail section. completion. The icons for tasks which are in progress, completed 
or which cannot be started until a dependent task completes are decorated to 
show the state of the task. The decorations in these screenshots are 
placeholders, they will be replaced with professionally drawn images. The 
screenshot below shows how the task &quot;Deploy a java project&quot; cannot be started 
until &quot;Create a java project&quot; is completed. The completion message for 
a task will contain a hyperlink to advance to the next task as defined by the 
schema of the task set. After a task has been completed it will be 
possible to review that task in read only mode.</p>
<p align="center"><img border="0" src="DeployJavaProject.PNG" width="286" height="416"></p>
<p>This sequence shows a task before it is started, while it is being run and 
after it has been completed.</p>
<table border="0" cellpadding="0" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="100%">
  <tr>
    <td width="33%">
    <img border="0" src="CreateJavaIntro.PNG"></td>
    <td width="33%">
    <img border="0" src="CreateJavaRun.PNG"></td>
    <td width="34%">
    <img border="0" src="CreateJavaComplete.PNG"></td>
  </tr>
</table>
<p>&nbsp;</p>
<p>A task set will have one root task, a task may have any number of child tasks. 
Each task can have a state of completed, not started or partially complete. The 
representation of the task explorer is configurable with an extension point, for 
Eclipse 3.2 a tree explorer will be included with the platform. By default the 
explorer for a task set when first opened is a tree; an attribute on the <code>
taskSet</code> 
element will allow that default to be overridden. If other explorers are 
registered the user will have the option from the view menu to switch between 
the different explorers.<br>
<br>
Task sets are registered using the existing cheat sheet, registered task sets will show up with 
standalone cheat sheets when the Help/Cheat sheets... menu is invoked. A task 
set may&nbsp;alternatively be opened from a file.</p>
<p>A task set manages the state of its child cheat sheets. If a cheat sheet 
appears as a task in multiple task sets it can have a different state for 
each task set it appears in. There may be cases where one cheat sheet needs 
to access data from another cheat sheet. Rather than introduce a way in which 
cheat sheets can access that data directly, a mechanism will be introduced in 
task sets which allows the state of a cheat sheet to be seeded based on 
variables from another cheat sheet in the same task set.</p>
<h3>Save state in a file (not only in metadata)</h3>
<p>In Eclipse 3.1 the state of a cheat sheet is persisted in project metadata. 
This will continue to be the default behavior in Eclipse 3.2 but the user will 
also be given the option to
save and restore the state of a cheat sheet or a task set using a file in a 
user project.</p>
<p>If a cheat sheet is opened from a task set the a new instance of the cheat sheet state will be created and that state will be saved with the state of 
the task set.</p>
<p>A&nbsp; button to set the state location will be added to the toolbar of the Cheat sheet view. This 
allows the user to specify a file where the state for the 
task set/cheat sheet will be stored. A restore command will be added to the 
drop-down menu for the cheat sheet view which allows the user to restore a cheat sheet 
or task set from saved state. In the case of a task set the state 
will be saved in multiple files, one for the task set itself and one for 
each cheat sheet which is part of the task set.<br>
&nbsp;</p>
<h3>More Pronounced Recognition of Success</h3>
<p>In Eclipse 3.1 there is no mechanism for the cheat sheet author to add a 
message to cheat sheet which only shows up after the step has been completed 
successfully. When the last step is completed the cheat sheet returns to the the intro 
step. For Eclipse 3.2 a new element kind &lt;onCompletion&gt; will be added to 
the schema which can be optional child elements of items or subitems. &lt;onCompletion&gt; 
contains text that will be displayed if a step is completed successfully. A step 
is considered to be completed successfully if the user performs it manually or if 
the cheat sheet completes without error an Action, command or resolution of a linkable reference. If an 
onCompletion message is displayed 
it will have a single button next to it, with tooltip &quot;go to next step&quot; or 
&quot;return to start&quot; depending on whether the &lt;onCompletion&gt; is a child of the final 
item. For example:</p>
<blockquote>
	<pre>&lt;item title=&quot;Verify the code you created&quot;&gt;
     &lt;description&gt;Press the button to programmatically check the contents of the class you created&lt;/description&gt;
     &lt;action
		class=&quot;org.eclipse.ui.cheatsheets.examples.CheckJavaCode&quot; 
		pluginId=&quot;org.eclipse.ui.cheatsheets.examples&quot;/&gt;
     &lt;onCompletion&gt;Congratulations - you have now successfully built hello world using the PDE!&lt;/onCompletion&gt;
&lt;/item&gt;</pre>
</blockquote>
<p>&nbsp;</p>
<p>&nbsp;</p>
<h3><br>
&nbsp;</h3>
<h3><br>
&nbsp;</h3>
<h3>&nbsp;</h3>



</HTML>